'\" t
.\"     Title: \fBmysqlfrm\fR
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 01/14/2017
.\"    Manual: MySQL Utilities
.\"    Source: MySQL 1.6.4
.\"  Language: English
.\"
.TH "\FBMYSQLFRM\FR" "1" "01/14/2017" "MySQL 1\&.6\&.4" "MySQL Utilities"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
mysqlfrm \- File reader for \&.frm files
.SH "SYNOPSIS"
.HP \w'\fBmysqlfrm\ [\fR\fB\fIoptions\fR\fR\fB]\fR\ 'u
\fBmysqlfrm [\fR\fB\fIoptions\fR\fR\fB]\fR
.SH "DESCRIPTION"
.PP
The
\fBmysqlfrm\fR
utility is designed as a recovery tool that reads \&.frm files and produces equivalent
\fICREATE\fR
statements from the table definition data found in the file\&. In most cases, the generated
\fICREATE\fR
statement is usable for recreating the table on another server, or for extended diagnostics\&. However, some features are not saved in the \&.frm files and therefore are omitted\&. The exclusions include but are not limited to:
.PP
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
foreign key constraints
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
auto increment number sequences
.RE
.PP
The
\fBmysqlfrm\fR
utility has two modes of operation\&. The default mode is designed to spawn an instance of an installed server by referencing the base directory using the
\fB\-\-basedir\fR
option, or by connecting to the server with the
\fB\-\-server\fR
option\&. The process does not alter the original \&.frm file(s)\&. This mode also requires the
\fB\-\-port\fR
option to specify a port to use for the spawned server\&. It must be different than the port for the installed server and no other server must be using the port\&. The spawned server is shutdown and all temporary files removed after the \&.frm files are read\&.
.PP
A diagnostic mode is available by using the
\fB\-\-diagnostic\fR
option\&. This switches the utility to read the \&.frm files byte\-by\-byte to recover as much information as possible\&. The diagnostic mode has additional limitations in that it cannot decipher character set or collation values without using an existing server installation specified with either the
\fB\-\-server\fR
or
\fB\-\-basedir\fR
option\&. This can also affect the size of the columns if the table uses multibyte characters\&. Use this mode when the default mode cannot read the file, or if a MySQL server is not installed on the host\&.
.PP
To read \&.frm files, list each file as a separate argument for the utility as shown in the following examples\&. You must specify the path for each \&.frm file you want to read or supply a path to a directory and all of the \&.frm files in that directory to be read\&.
.PP
You can specify the database name to be used in the resulting
\fICREATE\fR
statement by adding the name of the database followed by a colon to the \&.frm filename\&. For example, oltp:t1\&.frm uses \*(Aqoltp\*(Aq for the database name in the
\fICREATE\fR
statement\&. The optional database name can also be used with paths\&. For example,
\fI /home/me/oltp:t1\&.frm\fR
uses \*(Aqoltp\*(Aq as the database name\&. If you leave off the optional database name and include a path, the last folder is the database name\&. For example\fI /home/me/data1/t1\&.frm\fR
uses \*(Aqdata1\*(Aq as the database name\&. If you do not want to use the last folder as the database name, simply specify the colon like this:
\fI/home/me/data1/:t1\&.frm\fR\&. In this case, the database is omitted from the CREATE statement\&.
OPTIONS
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-help
.sp
show the program\*(Aqs help page
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-license
.sp
Display license information and exit\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-basedir=\fIbasedir\fR
.sp
The base directory for the server installed\&. Use this or
\fB\-\-server\fR
for the default mode\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-diagnostic
.sp
Turn on diagnostic mode to read \&.frm files byte\-by\-byte and generate best\-effort
\fICREATE\fR
statement\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-new\-storage\-engine=\fIengine\fR
.sp
Set the ENGINE= option for all \&.frm files read\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-port=\fIport\fR
.sp
The port to use for the spawned server in the default mode\&. Must be a free port\&. Required for default mode\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-server=\fIserver\fR
.sp
Connection information for a server\&. Use this option or
\fB\-\-basedir\fR
for the default mode\&. If provided with the diagnostic mode, the storage engine and character set information are validated against this server\&.
.sp
To connect to a server, it is necessary to specify connection parameters such as the user name, host name, password, and either a port or socket\&. MySQL Utilities provides a number of ways to supply this information\&. All of the methods require specifying your choice via a command\-line option such as \-\-server, \-\-master, \-\-slave, etc\&. The methods include the following in order of most secure to least secure\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Use login\-paths from your
\&.mylogin\&.cnf
file (encrypted, not visible)\&. Example :
\fIlogin\-path\fR[:\fIport\fR][:\fIsocket\fR]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Use a configuration file (unencrypted, not visible) Note: available in release\-1\&.5\&.0\&. Example :
\fIconfiguration\-file\-path\fR[:\fIsection\fR]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Specify the data on the command\-line (unencrypted, visible)\&. Example :
\fIuser\fR[:\fIpasswd\fR]@\fIhost\fR[:\fIport\fR][:\fIsocket\fR]
.RE
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-ssl\-ca
.sp
The path to a file that contains a list of trusted SSL CAs\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-ssl\-cert
.sp
The name of the SSL certificate file to use for establishing a secure connection\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-ssl\-key
.sp
The name of the SSL key file to use for establishing a secure connection\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-ssl
.sp
Specifies if the server connection requires use of SSL\&. If an encrypted connection cannot be established, the connection attempt fails\&. Default setting is 0 (SSL not required)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-show\-stats, \-s
.sp
Show file statistics and general table information for each \&.frm file read\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-start\-timeout=\fItimeout_in_seconds\fR
.sp
Number of seconds to wait for spawned server to start\&. The default is 10 seconds\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-user
.sp
Execute the spawned server using this user account\&. Permits the execution of the utility as one user but the spawned server as another\&. Required if running the utility as the root user (e\&.g\&. su or sudo)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-quiet
.sp
Turn off all messages for quiet execution except
\fICREATE\fR
statements and errors\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-verbose, \-v
.sp
Control how much information is displayed\&. For example,
\fB\-v\fR
= verbose,
\fB\-vv\fR
= more verbose,
\fB\-vvv\fR
= debug
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-version
.sp
Show program\*(Aqs version number and exit
.RE
NOTES.PP
Tables with certain storage engines cannot be read in the default mode\&. These include
\fIPARTITION\fR,
\fIPERFORMANCE_SCHEMA\fR\&. You must read these with the
\fB\-\-diagnostic\fR
mode\&.
.PP
Use the
\fB\-\-diagnostic\fR
mode for tables that fail to open correctly in the default mode or if there is no server installed on the host\&.
.PP
To change the storage engine in the
\fICREATE\fR
statement generated for all \&.frm files read, use the
\fB\-\-new\-storage\-engine\fR
option
.PP
To turn off all messages except the
\fICREATE\fR
statement and warnings or errors, use the
\fB\-\-quiet\fR
option\&.
.PP
Use the
\fB\-\-show\-stats\fR
option to see file statistics for each \&.frm file\&.
.PP
If you need to run the utility with elevated privileges, use the
\fB\-\-user\fR
option to execute the spawned server using a normal user account\&.
.PP
If you encounter connection or similar errors when running in default mode, re\-run the command with the
\fB\-\-verbose\fR
option and view the output from the spawned server and repair any errors in launching the server\&. If
\fBmysqlfrm\fR
fails in the middle, you may need to manually shutdown the server on the port specified with
\fB\-\-port\fR\&.
EXAMPLES.PP
The following example reads a single \&.frm file in the default mode from the current working directory using the server installed in
/usr/local/bin/mysql
and port 3333 for the spawned server\&. Notice the use of the
\fIdb:table\&.frm\fR
format for specifying the database name for the table\&. The database name appears to the left of \*(Aq:\*(Aq and the \&.frm name to the right\&. In this case, we have database = test1 and table = city, so the
CREATE
statement reads
CREATE TABLE test1\&.city\&.
.sp
.if n \{\
.RS 4
.\}
.nf
shell> \fBmysqlfrm \-\-basedir=/usr/local/bin/mysql test1:city\&.frm \-\-port=3333\fR
# Starting the spawned server on port 3333 \&.\&.\&. done\&.
# Reading \&.frm files
#
# Reading the city\&.frm file\&.
#
# CREATE statement for city\&.frm:
#
CREATE TABLE `test1`\&.`city` (
  `city_id` smallint(5) unsigned NOT NULL AUTO_INCREMENT,
  `city` varchar(50) NOT NULL,
  `country_id` smallint(5) unsigned NOT NULL,
  `last_update` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`city_id`),
  KEY `idx_fk_country_id` (`country_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8
#\&.\&.\&.done\&.
.fi
.if n \{\
.RE
.\}
.PP
The following demonstrates reading multiple \&.frm files in the default mode using a running server\&. The \&.frm files are located in different folders\&. Notice the use of the database name option for each of the files\&. The t1 file was given the database name temp1 since that is the folder in which it resides, t2 was given db1 since that was specified in the path, and t3 was not given a database name since we used the \*(Aq:\*(Aq without providing a database name\&.
.sp
.if n \{\
.RS 4
.\}
.nf
shell> \fBmysqlfrm \-\-server=root:pass@localhost:3306 /mysql/data/temp1/t1\&.frm \e\fR
          \fB/mysql/data/temp2/db1:t2\&.frm \-\-port=3310\fR
# Starting the spawned server on port 3333 \&.\&.\&. done\&.
# Reading \&.frm files
#
#
# Reading the t1\&.frm file\&.
#
# CREATE statement for \&./mysql\-test/std_data/frm_files/t1\&.frm:
#
CREATE TABLE `temp1`\&.`t1` (
  `a` int(11) DEFAULT NULL
) ENGINE=MyISAM DEFAULT CHARSET=latin1
# Reading the t2\&.frm file\&.
#
# CREATE statement for \&./mysql\-test/std_data/frm_files/t2\&.frm:
#
CREATE TABLE `db1`\&.`t2` (
  `a` int(11) DEFAULT NULL
) ENGINE=MyISAM DEFAULT CHARSET=latin1
#
# Reading the t3\&.frm file\&.
#
# CREATE statement for \&./mysql\-test/std_data/frm_files/t3\&.frm:
#
CREATE TABLE `t3` (
  `a` int(11) DEFAULT NULL
) ENGINE=MyISAM DEFAULT CHARSET=latin1
#\&.\&.\&.done\&.
.fi
.if n \{\
.RE
.\}
.PP
The following demonstrates running the utility in diagnostic mode to read all of the \&.frm files in a directory\&.
.sp
.if n \{\
.RS 4
.\}
.nf
shell> \fBmysqlfrm \-\-diagnostic /mysql/data/sakila\fR
# WARNING: Cannot generate character set or collation names without the \-\-server option\&.
# CAUTION: The diagnostic mode is a best\-effort parse of the \&.frm file\&. As such, it may not identify all of the components of the table correctly\&. This is especially true for damaged files\&. It will also not read the default values for the columns and the resulting statement may not be syntactically correct\&.
# Reading \&.frm file for /mysql/data/sakila/city\&.frm:
# The \&.frm file is a TABLE\&.
# CREATE TABLE Statement:
CREATE TABLE `city` (
  `city_id` smallint(5) unsigned NOT NULL AUTO_INCREMENT,
  `city` varchar(150) NOT NULL,
  `country_id` smallint(5) unsigned NOT NULL,
  `last_update` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY `PRIMARY` (`city_id`),
KEY `idx_fk_country_id` (`country_id`)
) ENGINE=InnoDB;
#\&.\&.\&.done\&.
.fi
.if n \{\
.RE
.\}
.sp
PERMISSIONS REQUIRED.PP
The permissions for using
\fBmysqlfrm\fR
vary and depend entirely on how you use it\&. If you use the utility to read \&.frm files in a protected folder like the example above (in either mode), you must have the ability to run the spawned server with privileges that allow you to read the protected files\&. For example, you could use a user account that has root\-level privileges\&.
.PP
If you use the utility with a server connection, the user you use to connect must have the ability to read system variables at a minimum including read access to the mysql database\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
You should never use the root user to spawn the server nor should you use the mysql user when spawning the server or running the utility\&.
.sp .5v
.RE
.SH "COPYRIGHT"
.br
.PP
Copyright \(co 2006, 2017, Oracle and/or its affiliates. All rights reserved.
.PP
This documentation is free software; you can redistribute it and/or modify it only under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 of the License.
.PP
This documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public License along with the program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA or see http://www.gnu.org/licenses/.
.sp
.SH "SEE ALSO"
For more information, please refer to the MySQL Utilities and Fabric
documentation, which is available online at
http://dev.mysql.com/doc/index-utils-fabric.html
.SH AUTHOR
Oracle Corporation (http://dev.mysql.com/).
